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Foreword 


Some basic Linux skills and general IT knowledge is assumed throughout parts of this document. For 
this reason, this guide does not cover topics such as basic networking, CD burning, partitioning scheme 
design, varying infrastructure methodologies, validity of install, and other unmentioned topics or 
variations of installation. To find out more about any of the steps in this document, or to learn more 
about any particular ViciBox install or ViciDial setup, we suggest you search and ask questions on the 
ViciDial forums at http://www.vicidial.org/VICIDIALforum/. In addition, you can find more 
information with regards to Linux, OpenSuSE, and other general topics by using Google and/or the 
official OpenSuSE Leap v.42.1 documentation located at http://activedoc.opensuse.org/. 


ViciBox is a self-contained installation CD based upon the OpenSuSE v.42.1 Linux distribution. It 
includes both online as well as offline installation capabilities. It is packaged as a LiveCD that can be 
used as an installation medium, rescue disk, or hardware testing resource. 


Paid Support is available through the ViciDial Group (www.vicidial.com) to help with any portion of a 
ViciBox or ViciDial installation. Custom development of both ViciBox and ViciDial are offered 
through the ViciDial Group as well. 


Alternatively, if the prospect of installing and maintaining your own ViciBox/ViciDial cluster seems 
too daunting, the ViciHost (www.vicihost.com) service is available to give you all the features and 
benefits of ViciDial without having to maintain physical servers or worry about installing and updating 
ViciBox. 


Compatibility and Prerequisites 


As of this writing the current version of ViciBox is v.7.0.0. It is built with the following software: 
e OpenSuSE Leap v.42.1 
e Linux Kernel v.4.1.15 
e Asterisk v.11.21.0-vici 
e DAHDI v.2.11.0 


e Amfeltec VoiceSync v.1.3.8 
e OpenR2 v.1.3.3 


For an optimal experience with ViciDial and ViciBox, the following minimum hardware specifications 
should be used: 

e Quad-Core CPU 2.0Ghz 

e 4GB RAM 

e 160GB 7200rpm enterprise-grade SATA drive (Seagate ES, Hitachi UltraStar, WD RE4, etc) 


Optionally, in addition to the above specifications, the following can be used for a more robust server: 
e 8GB RAM (ECC if available) 
e Two hot-swap 500GB enterprise-grade SATA or SAS drives in RAID-1 
ViciBox “Express” 


A ViciBox “Express” system consists of all major roles including Database, Web, and Telephony 
server. Using the minimum hardware specifications listed above, this would be well suited for a call 
center up to 15 agents doing outbound calling with call recordings at a 4:1 ratio. When used for 
inbound the same minimum hardware specifications are acceptable for up to 25 agents. Please note that 
the figures presented are a conservative guideline and that your actual system capacity is heavily 
determined by the number of agents, number of leads, concurrent call count, dialing ratio if applicable, 
campaign settings, and the general capacity of the hardware. It is for this reason that additional 
specifications were provided should you run into any minor load issues. Particular attention should be 
paid to the size of the hard-drive(s) installed in the system if you record your calls. The most frequent 
issue new customers experience is a crashed server due to the hard drive filling up with recordings. 


ViciBox “Cluster” 


Clustering is where multiple individual servers perform specific roles within ViciDial. Those roles are 
Database, Web, Telephony, and Archive server. Clustering should generally be used for an install 
consisting of more then 20 outbound agents or 30 inbound agents. If you do not know or are unsure of 
whether you should perform a clustered install please consult with the free community-based ViciDial 
forums or paid-for ViciDial Group for support. Please be prepared to explain your planned installation 
including number of agents, call type (Outbound/Blended/Inbound), expected dialing ratio or 
concurrent call volume, archival requirements, and any other unique processes or requirements you 
may have. This will help generate an accurate answer to your questions. 


A minimum starting cluster would consist of a single Telephony server and a combined Database and 
Web server. A three server cluster, whereby there is at least a single server dedicated to performing the 
roll of a Database, Web, and Telephony server is the more robust option and requires little to no 
reconfiguration as the cluster grows in size. 


ViciDial scales horizontally for all roles except the Database. For this reason, you will need to spend 
extra time deciding on the hardware specifications of your Database server. The specifications we 
recommend for a database server up to 150 agents is as follows: 

e Quad-Core CPU 2.0Ghz+ 


e 8GB ECC Ram 

e 2-drive 240GB+ SSD (Intel 530, 730, etc) configured in RAID-1 on a Linux software RAID or 
SSD-optimized raid card (LSI FastPath MegaRAID, etc) 

e Redundant Power Supplies with each on a different battery back-up 


To add to the above specification for handling up to 300 agents would be as follows: 
e Two Quad-Core CPU 2.0Ghz+ 
e 16GB ECC Ram 
e Two Separate 500GB enterprise-grade SATA drive for the OS in a RAID-1 


For a 500 agent Database server, adding to the specification, would be as follows: 
e Two Hex-Core CPU 2.0Ghz+ 
e 32GB+ ECC Ram 
e 4-Drive 240GB+ RAID-10 on SSD (Intel 530, 730, etc) with SSD-optimized RAID card (LSI 
FastPath MegaRAID, etc) or Linux software RAID 
e Two Separate 500GB enterprise-grade SATA drive for the OS in a RAID-1 


Cluster Dimensioning 


Clustering of the Web and Telephony roles in vicidial is done horizontally. This means that as your 
capacity grows you simply add more servers to your cluster to compensate. A cluster should always 
start with at least one dedicated Telephony server and a combination Database and Web server. If your 
total agent capacity will be less then 50 agents then you can use the optional server specifications 
provided under the “Compatibility and Prerequisite” section for your Database. All other clustering 
options should use one of the database-specific specifications listed under the “ViciBox Cluster” 
section. All Web and Telephony servers just need to adhere to the base specifications listed under the 
“Compatibility and Prerequisite” section. 


In general, you can expect to get 25 outbound agents dialing 4:1 ratio or 50 inbound agents with 100 
concurrent lines on a dedicated Telephony server using the standard hardware specification. It is 
recommended to use the optional specification for recording long call durations or inbound call centers. 


A dedicated Web Server will handle approximately 150 agents using the standard hardware 
specification. When more then one web server is used it is recommended to configure a third machine 
to act as a load-balancer for the agent interface between the multiple web servers. The agent will 
initially go to the load balancer to log in and then be redirected to one of the back-end servers. 
Configuration of the load balancer is done through the use of the mod_proxy_balancer module in 
Apache and is not covered by this document. There are many examples and walk-throughs available by 
searching the internet. Alternatively, the ViciDial Group can install and set-up a load balancer for you 
through paid support options. 


Below are some examples of dimensioning for various agent loads: 


50 Agents Outbound 4:1 


e Optional Hardware Specification for Database/Web 
e Two Telephony Servers - Standard or Optional specification 


75 Agent Outbound 4:1 
e Standard Database specification 
e One Web server — Standard or Optional specification 
¢ Three Telephony servers - Standard or Optional specification 


100 Agent Outbound 4:1 
e Standard Database specification 
* One Web server — Standard or Optional specification 
e Four Telephony servers - Standard or Optional specification 


200 Agent Outbound 4:1 
e 300-agent Database specification 
* Two Web servers — Standard or Optional specification 
¢ Eight Telephony servers - Standard or Optional specification 
e Optionally one Web server to act as login load balancer and administration — Standard or 
Optional Specifications 


500 Agent Outbound 4:1 
e 500-agent Database specification 
e Four Web servers — Standard or Optional Specification 
e Twenty Telephony Servers - Standard or Optional Specification 
e One web server to act as login load balancer and administration - Standard or Optional 
Specification 


100 Agent Inbound 
e Standard Database Specification 
e One Web server — Standard or Optional specification 
e Two Telephony servers - Standard or Optional specification 


200 Agent Inbound 
e 300-agent Database specification 
* Two Web servers — Standard or Optional specification 
e Four Telephony servers - Optional specification 
e Optionally one Web server to act as login load balancer and administration — Standard or 
Optional Specifications 


500 Agent Inbound 
e 500-agent Database specification 
¢ Four Web servers — Standard or Optional Specification 


¢ Ten Telephony Servers - Optional Specification 
* One web server to act as login load balancer and administration - Standard or Optional 
Specification 


A dedicated Archive server was not listed in any of the above dimensioning guidelines but will be 
needed for most cluster installations. While ViciBox does provide an option to install as a dedicated 
Archive server it is not required to do so. Any NAS or server that can provide FTP for ViciDial to 
upload recordings and then HTTP service to access those recordings via a web browser can be used as 
an archive server. We recommend you have at least 1TB of space available on an archive server for 
storage. Hardware requirements for ViciBox to install as an archive server are minimal. A dual-core 
CPU and 2GB or more of RAM is all that is needed. It is highly recommended that you use at least a 
RAID-1 on your archive server to prevent data loss. 


It should also be noted that the Telephony server role is limited by software and not hardware during 
dimensioning. This means that it does not scale linearly with hardware specifications. If you doubled 
the hardware capacity you would not double the call or agent handling capacity. This is because of the 
manner in which Asterisk scales starts to break down around or above 250 concurrent internal channels. 
Considering one agent in a call can potentially use 4 active internal channels we chose 25 agents 
outbound as our general rule of thumb. There is no imposed limit to prevent you from putting as many 
agents or calls on a server as you want, but the chances of the asterisk process crashing resulting in 
your call center being down greatly increase above the guidelines given. It is the opinion of the 
ViciDial Group that it is better to have an extra server and gain stability in the process. This is also 
cheaper once you calculate the cost of an hour of downtime versus the cost of the spare server. 


Installation Notes 


The standard 'root' password is 'vicidial' on all installion media. To login you simply type 'root' at the 
“Login” prompt and 'vicidial' at the “Password” prompt. 


ViciBox is available only in a x86_ 64 64-bit architecture. It is not available in a 32-bit architecture or 
for non x86 based architectures like ARM or PowerPC. Any modern CPU released after 2004 should 
not have any issues installing or running ViciBox. 


ViciBox v.7.0 ships by default with Asterisk v.11 installed. If you are adding a Telephony server to an 
existing cluster using ViciBox v.7.0 it will be necessary to either upgrade the cluster to a recent version 
of ViciDial that has Asterisk v.11 support or downgrade Asterisk to v.1.8. Downgrading Asterisk is not 
included as part of this installation manual. 


Virtualization is NOT recommended for any portion of ViciDial except the Archive server. Due to the 
nature of ViciDial all components operate in a real time capacity. This is especially true for the 
Telephony server since it handles the RTP audio from agents and carriers. Virtualized installations will 
not be supported by the ViciDial Group. Support for virtualized installations may be available through 
the ViciDial forums. 


The documentation is split up into two mandatory phases and one optional phase. Phase 1 consists of 


installing the Operating System onto the server and configuring the base requirements necessary for 
ViciDial to work. This includes things like RAID configuration, third-party drivers, and other 
considerations. Phase 1 must be completed and network connectivity established prior to any remote 
installation assistance. The server configuration, such as non-privileged users and network 
configuration, can be set here. 


Phase 1.5 are optional and recommended installation steps. This phase is primarily used to update the 
operating system with any relevant updates and configure additional options like the Date and Time, 
etc. This would also be the appropriate time to do any custom work to the operating system and it's 
configuration prior to the installation of Phase 2. 


Phase 2 is the final installation step that installs and configures ViciDial on the server. This step should 
only be done when the server is in it's final production environment. If this is a cluster installation, then 
the Database server MUST be completed prior to attempting any other servers. The installer will not 
allow an install where it can not connect to the Database. If you have a planned Archive server using 
ViciBox, that should be installed prior to any Telephony servers. After installing the database, it's 
recommended to install the web server, archive server, and then telephony servers in that order. 
Telephony and Web servers should have the phase 2 installation done one at a time to prevent any 
issues. 


Some conventions used throughout the installation instructions are as follows: 

e Commands to type will be contained within a single quote and should be typed exactly as how 
it appears between the quotes, example: ‘command here’ 

e Keys to press on the keyboard will be in all caps; three examples: ENTER ESC F3 

e Key sequences, or a multiple key press, will be capitalized with a dash between each key to 
press simultaneously; five examples: ALT-N ALT-Q CTRL-I CTRL-ALT-F1 

* Commentary and Notes will be italicized explaining various options or explanations for that 
stage of the installation. 

e Each section has a paragraph explaining the objective of that phase of the installation, as well as 
a footer saying where to proceed to the next section. 

e The command prompt is signified by a red pound (#) sign and the cursor. Example: linux # 


Phase 1 — OS Installation 


To perform the OS Installation using the standard ISO perform the following steps: 
1. Download the current ViciBox Server ISO from 
http://download.vicidial.com/iso/vicibox/server/ 
Burn ISO to CD/DVD and boot from the disk 
At the boot screen, press the F3 key to select the Video Mode options 
Using the arrow keys, highlight the 'Text Mode’ option and press the ENTER key 
Using the arrow keys, highlight the 'ViciBox v.7' option in the center of the screen and press the 
ENTER key. 
6. At the ViciDial license screen, press CTRL-A to agree to the license agreement 


a 


16. 


18. 


19, 


20. 


21. 


22. 


23: 


24. 


25: 


Press ALT-N to select 'Next' and proceed with the boot-up sequence 

At the login prompt, type 'root' and press ENTER. You may have to hit ENTER after a minute to 
see the login prompt. It sometimes gets overwritten on the screen from the boot process. 

At the Password prompt, type 'vicidial' and press ENTER 


. At the command prompt, type 'os-install' and press ENTER. Jf there is any custom 


configuration to be done to this server prior to OS installation, it should be done before this 
Step. 


. To change the default langauge, press ALT-L and select your preferred language 


To change the default keyboard layout, press ALT-K and select your preferred layout 


. Press ALT-N to agree to the license displayed and move on to the next screen 


To change the displayed region, press ALT-E and use the up and down arrow keys to select your 
preferred region. Alternatively, the TAB key can be used to switch between windows on this 
screen and proceeding screens. 


. To change the displayed Time Zone, press ALT-Z and use the up and down arrow keys to select 


your preferred time zone. 
Press ALT-N to accept the selected Region and Time Zone and move on to the next screen 


. To accept the default partitioning scheme press ALT-N to proceed to the next screen. The 


partitioning module in OpenSuSE is somewhat inconsistent. You should see in the summary list 
"Create swap volume /dev/sdal" and "Create root volume /dev/sda2". If not, please read the 
partitioning notes under the Miscellaneous section at the end of this document prior to 
proceeding. 

Type in the new 'root' password that you would like to use. For the purposes of this document 
you would type ‘vicidial’. 

Press ALT-F to move to the password confirmation dialog, and re-type in the new root password 
you entered in the previous step. 

Press ALT-N to select Next and continue with the installation. Zf the passwords to not match, 
are blank, or are not considered high-security passwords, you will be presented with an 
additional dialog box. You will need to either correct the passwords if they are blank or don't 
match, or chose whether to accept the password and continue or input a new password. 

Press ALT-I to install the operating system according to the installation summary presented. You 
can use the up and down arrows keys to scroll through the installation summary. You can press 
ENTER on any highlighted section to adjust those installation options, although those options 
will not be covered by this document. This is the point of no-return, do not proceed past here if 
this server already has important data on it. 

Press ALT-I to confirm the destruction of the host system's old installation and installation of 
the new operating system. You will be presented with a screen showing installation progress 
and logs. At this point all data on the hard drive has been destroyed. 

When prompted, press ALT-N and then press ENTER to reboot the server. You may also use the 
left and right arrow keys to highlight "Reboot Now" and press ENTER. It is a good idea to 
remove the CD from the drive during reboot as well as setting the BIOS to boot from the hard- 
drive before any other devices. 

When the Login prompt comes up after the reboot, log in as the 'root' user using the password 
entered in step 18 above. 

At the command prompt, type 'reboot' and press ENTER. Due to a quirk in the OpenSuSE 
LiveCD installer it is necessary to reboot the server a second time to properly initialize the 
network. This is only required once after the LiveCD has finished it's installation. 


The Phase-1 OS Installation is now complete. Please proceed to the Phase 1.5 installation instructions. 
You will need to complete the required portions of Phase 1.5 before continuing to Phase 2. 


Phase 1.5 — Required, Recommended, and Optional configuration items 


This section contains small miniaturized installation and configuration instructions for various things. 
The only required section is the "Network Configuration" section. It is required that all ViciDial servers 
be able to communicate freely with each other on the network. The other sections include 
recommended and optional configuration information. 


Phase 1.5 - Network Configuration REQUIRED CONFIGURATION 


l. 
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11. 


12. 
13. 
14. 


If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 
login. The password can not be recovered easily and requires offline intervention. 

Type 'yast lan' and press ENTER Optionally, you can type 'yast' and navigate to the network 
configuration by going to Network Devices --> Network Settings. 

Using the TAB key, press it until the network card is selected. If you have multiple network 
cards, select the one that will be used to communicate with the other ViciDial servers. 

Press ALT-I to edit the network configuration for that interface. 

Press ALT-T to select "Statically assigned IP Address". The server should always have a 
statically assigned IP address, no exceptions. 

Press ALT-I to move the cursor to the "IP Address" field, it should be highlighted. Optionally, 
you can use the TAB key to move between fields and windows on this screen and the proceeding 
screens. 

Enter the IP Address for this interface. This should primarily be the internal IP Address if this is 
the first network card. If this is the second network card, this would be the IP Address provided 
to you by your ISP if not behind a router. 

Press ALT-G to view the General options for this network card. 

Press ALT-Z to select the Firewall Zone for this Interface. 


. Using the up and down arrow keys, select "Internal Zone" and press ENTER. Jf this is the 


second network card connected directly to the internet, select "External Zone" instead. 
Optionally, if you are going to disable the built-in firewall, select "Internal Zone" for all 
network cards to prevent the system from being locked out should the firewall be turned on by 
mistake. 

Press ALT-N to accept network card configuration and return to the Overview screen. 
Optionally, if you have a second network card to configure, you can repeat steps 3 to 11 by 
select the second network card in step3. 

Press ALT-S to change to the Hostname/DNS screen 

Press ALT-T to select the Hostname field 

Enter the unique Hostname of this server. All servers MUST have a unique hostname for the 
installation to properly continue. The installer will fail if all hostnames are not unique. We 
recommend using DB(x), Web(x), and Vici(x) for the hostnames while replacing the (x) with the 
numerical sequence of the installed server. For instance, the first Web server would be Web], 
the second Web server would be Web2, the first Telephony server would be Vicil, the second 


Telephony server would be Vici2, etc. Try to choose a hostname that relates to the function of 
the server and not an arbitrary name to avoid confusion. Names like 'Zeus', ‘Batman’, 'Mickey 
Mouse’, etc, do not properly convey the function of the server to anyone who may be unfamiliar 
with it. 

15. Press ALT-D to select the Domain field 

16. Enter the Domain name for this server. If you do not have or know your Domain, enter 
‘vici.local'’. 

17. Press ALT-1 to select Name Server 1 field 

18. Enter the primary name server to use on your network. If you are behind a router this is 
typically the router IP. If you do not have or know your DNS server's IP then enter '8.8.8.8' to 
use Google's DNS. 

19. Press ALT-2 to select Name Server 2 field 

20. Enter the secondary name server ot use on your network. If you do not know or have a 
secondary DNS server, then enter '8.8.4.4' to use Google's DNS 

21. Press ALT-U to change to the Routing screen 

22. Press ALT-F to select the Default IPv4 Gateway field 

23. Enter the default gateway IP for your network. This will be the IP address of your router. This is 
determined by your local network/router and can not be determined remotely. If you have a 
second network interface card that is directly connected to an ISP then you will enter the 
gateway IP provided by the ISP here. 

24. Press ALT-O to select Ok and make the network configuration changes. You can review the 
changes by pressing ALT-V for the overview, ALT-S for the Hostname/DNS configuration, and 
ALT-U for the routing configuration if you want to review them before proceeding. 

25. Verify proper network connectivity by trying to ping something on the internet, I.E. 'ping 
google.com’. Press CTRL-C to stop the ping when satisfied. If you do not have internet 
connectivity try pinging another server or workstation on the network. Depending upon the 
complexity of your network configuration it might be necessary to reboot to enact network 
configurations. 


In addition to basic network configuration, you can configure the built-in firewall by typing 'yast 
firewall’ or select Security --> Firewall after typing 'yast'. The Phase 2 installation script will ask you if 
you want to enable or disable the firewall and will automatically open up the appropriate ports for 
ViciDial to function if left enabled. You only need to configure advanced options if wanted. 


Phase 1.5 — Install Updates Recommended 

1. Ifnot already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 
login. The password can not be recovered easily and requires offline intervention. 

2. Type 'zypper up -y' to begin the update process. If this step fails, then try again later. The 
OpenSuSE repositories go into maintenance at certain times and can be unavailable, making 
updates impossible to happen. 

3. Type 'reboot' to cleanly load and apply any updates that were applied to your system. 


Phase 1.5 — Configure Time Zone Recommended 
1. Ifnot already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 


login. The password can not be recovered easily and requires offline intervention. 

Type 'yast timezone' to enter the time zone configuration screen 

Type ALT-R to move to the region selection window. 

Using the up and down arrow keys, select the appropriate region for this server's location. 
Type ALT-Z or press TAB to move to the Time Zone window 

Using the up and down arrow keys, select the appropriate time zone for this server's location. 
Type ALT-O when finished to accept the configured region and time zone for this server. 
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Phase 1.5- Changing the root password Optional (Read completely first) 

1. Ifnot already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 
login. The password can not be recovered easily and requires offline intervention 

2. Type 'passwd' at the command prompt to start the password change processes 

Type in the new root password at the “New Password:” prompt and press ENTER 
4. Verify the password by typing it in again at the “Retype new password:” prompt and press 
ENTER. 


iss) 


DO NOT LOSE THIS PASSWORD! It is always required for any remote support needed at the 
operating system level and can not easily be recovered. Please chose a password that contains letters 
and numbers and is at least 8 characters long. Mixing upper and lower case letters is advisable and 
specialty characters like @ =/ + - ! ~ can also be used.. Avoid choosing passwords that are overly 
complex, random, or hard to remember. This just leads to people writing the password down and 
leaving it stuck to their monitor. 


One simple method is to take a word and replace a few letters with numbers and capitalize it. For 
instance, if we take the standard root password 'vicidial' and apply this logic we would end up with 
"Vicldlal'. While 8 characters is the minimum recommended length, 12 or more characters is optimal. 
Avoid using a strong password generator as the password will almost assuredly be forgotten or written 
down which negates the whole point of a strong password to begin with. Also do not use any password 
contained within this document or used as an agent/manager login. The root password should be unique 
and not shared with anyone other then system administrators. 


If the 'ssh' service (TCP Port 22) is not exposed or connected to the internet to begin with then it is 
arguably safe to leave the stardard root password of 'vicidial'. If the server IS accessible via SSH from 
the internet then it is highly recommended to change the root password or otherwise restrict access to it 
externally. If someone is able to log in as root they will be able to do whatever they want with your 
server. Most of the time this involves using your system for Spam, DDoS attacks, bitcoin mining, and 
toll fraud. All of which have a very detrimental effect on your ViciDial system. 


Phase 2 - ViciBox "Express" Installation 


This section contains installation instructions for the "Express" installation method of ViciBox. Please 
read the "ViciBox Express" section at the beginning of this document before continuing. The time 


required to split an Express installation into a cluster later can easily surpass the amount of time 
normally required to set-up a Cluster from the start. 


To install ViciDial using the ViciBox "Express" method, run the following: 

1. Ifnot already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 
login. The password can not be recovered easily and requires offline intervention. 

2. Type 'vicibox-express' and press ENTER. You will see the installer start in ViciBox Express 
mode. It will prompt for any further input it needs while installing. 

3. When the installer indicates that it has completed, type 'reboot' and press ENTER to reboot the 
system and cleanly load all changes and ViciDial. 

4. From a web browser on a workstation, type in the IP Address of your server and press ENTER. 

5. At this point you should see the ViciDial welcome page. The installation is now complete. 


Please refer to the ViciDial Manual for further instructions on logging into ViciDial and configuring the 
various options. The default administrative user for ViciDial is '6666' with the password of '1234'. You 
do not need to complete any other Phase 2 instructions at this point. 


Please use caution when selecting system passwords. If you keep the passwords too simple you open 
yourself up to hackers committing toll fraud through your system. A secure password contains more 
then 8 characters and consists of one lowercase letter, one uppercase letter, and one numeral. An 
example of a secure password would be 'nebl6HE0u25a0Gt'. Please DO NOT use this password, it is 
ONLY an example. The default phone registration password and server password has already been 
randomized in your install. When changing them, please keep the above secure password requirements 
in mind. 


Phase 2 - ViciBox "Cluster" Installation 


This section contains installation instructions for the "Cluster" installation method of ViciBox. Please 
read the "ViciBox Cluster" section at the beginning of this document before continuing. A cluster with 
underpowered resources can potentially cause problems that could result in downtime and loss of 
productivity. Server downtime can easily outweigh the financial savings from under-powering a 
Cluster. Free community support is available on the forums as well as paid support through the 
ViciDial Group if you have any questions on properly dimensioning or installing a cluster. 


Due to the nature of clustering and the ViciBox installer, all clusters, regardless of size, must be 
installed in the following order: 

1. Database Server 

2. Archive Server if applicable 

3. Web Server 

4. Telephony Server 


The installer will refuse to run without being able to properly connect to the database. If you have a 
slave database, make sure you are putting in the IP Address of ONLY the master database when the 


installer asks. You must also have at least one Web server installed prior to installing any Telephony 
servers in order for the Audio Store and other web-based ViciDial features to be properly set-up and 
enabled. Best practice is to run the installations linearly, starting with the DB server and progressing 
your way on to the next server only when the current one has completed it's install. This ensures that 
things are installed properly and in the right order to prevent any issues. 


Make sure to write down the IP Address' of all your servers so that you can refer to them later during 
the installation. This will not only help during the installation but also shorten the time it takes to 
diagnose and correct any issues that may come up. If possible, map out your IP address' so that they are 
linear in progression and make sense. For instance, 192.168.0.10 would be a database, following by 
192.168.0.11 for the web server, and then 192.168.0.12 and above for the telephony servers. 


To install ViciDial using the ViciBox "Cluster" method, run the following: 

1. Ifnot already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 
login. The password can not be recovered easily and requires offline intervention. 

2. Type 'vicibox-install' and press ENTER. The installer will start and prompt you for all further 
configuration information. 

3. When the installer indicates that it has completed, type 'reboot' and press ENTER to reboot the 
system and cleanly load all changes and ViciDial. 


Installation of a cluster can not be verified until the Web server is installed at a minimum. To verify, 
type the web servers IP address from a workstation and you should see the ViciDial welcome page. The 
default administrative user is '6666' and password '1234'. Please refer to the ViciDial Manual for 
information on initially logging in and configuring ViciDial from the web interface. 


Once you have logged into the web interface, you can verify that the cluster is working properly by 
clicking on the Report section on the left, and then clicking the + next to where it says "Server" at the 
bottom. It will list the time on all connected machines in the cluster. When properly set-up, all 
machines should be within one to two seconds of each other with the exception of the Database server 
entry. You should all see all the hostnames of the Telephony server and the Database server. It is correct 
for the Database server entry to not show the correct time, however, at the bottom the "DB Time" field 
should match. 


Phase 2 - ViciBox "Restore" Server Replacement in a Cluster 


The restore method is not a complete end-all solution for replacing a server in a ViciBox cluster. It is a 
tool mean't to ease and speed the replacement of a server. It can not be used for a database and does not 
copy any custom configurations, crontab entries, or other things done on a server. It is advised you 
maintain back-ups of your servers to prevent data loss and additional downtime during replacement. 


In order to use the restore option you will need to know your database connection information. If the 
database was installed with ViciBox prior to v.4.0 or then you will also need to know the SVN revision 
running on your cluster. The safest method for determining the SVN revision it to run 'svn info' in 

the /usr/src/astguiclient/trunk directory on your database server. If your database was not installed using 


ViciBox then you will have to ask the system administrator what SVN revision was used. 


To run the ViciBox restore, perform the following commands: 

1. Ifnot already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the 
password prompt. If you changed the root password, or someone else has, you will need it to 
login. The password can not be recovered easily and requires offline intervention. 

2. Type 'vicibox-install --restore' at the command prompt and press ENTER. The installer will 
start in the special restore mode and prompt you for further information. 

3. When the installer indicates that it has completed, type 'reboot' and press ENTER to reboot the 
system and cleanly load all changed and ViciDial. 


ViciBox Upgrade 


There are currently two methods for upgrading ViciBox. Method one is to do all steps and procedures 
manually according to the documentation located at /usr/src/astguiclient/ UPGRADE. The second 
method involves using a program called 'vicibox-upgrade' to perform the schema and SVN upgrade for 
you leaving just the changes to configuration files. The vicibox-upgrade program will also add the 
vicibox table on the database if it doesn't exist making your cluster compatible with newer features 
introduced since ViciBox v.4.0. 


The preferred method is to start on the database. It is highly advised you take a back-up of the database 
prior to performing the upgrade. Once the database is done you would then run vicibox-upgrade on the 
web servers, followed by the dialers. You can use the --help flag to view all run-time options. Please 
keep in mind that the upgrade program does not modify any configuration files like 
/etc/asterisk/extensions.conf. These will still need to be upgraded by hand. This is merely a tool to help 
upgrade the database and make sure the same SVN revision is installed on all servers. 


The program has been tested to run properly on ViciBox v.3.0 and above. You can simply copy it to the 
older servers to use it's features. As mentioned previously, always start with the database first. It is 
imperative that the database be upgraded first before any other systems in a cluster are attempted. If 
you are upgrading an 'express' installation then you only need to run vicibox-upgrade once. 


When ran on a system that was installed prior to ViciBox v.4.0 you will be prompted for the roles that 
each server performs. You will then be prompted on whether or not to insert the records into the vicibox 
table if it exists at the end of the upgrade. The recommendation is to say Yes to inserting the records 
into the vicibox table. This will help in the maintenance of your installation in the future. 


Miscellaneous, Tips and Tricks, Issues, and other commentary 
Installation Partitioning 
The partitioning module included in OpenSuSE has become less consistent in how it calculates the 


partitioning scheme. The default paritioning scheme that it should be creating consists of a 4GB "swap" 
partition and a "/" root partition containing the rest of the drive. Unfortunately this does not work 


consistently if there was a previously installed linux swap partition. Instead it will use that swap 
partition, create another 4GB partition, and then configure the rest of the drive as the "/" root partition. 
The easiest way to fix this is to wipe out the partition table using the following command from the 
LiveCD prior to typing 'os-install' during Phase 1: 


1. Type 'dd if=/dev/zero of=/dev/sda bs=512' and press ENTER 
2. Type 'reboot' to reboot the server and re-attempt your install 


CAUTION: Do not run this command on any active server as it will destroy all data on the drive 
requiring a specialist to recover it. You have been warned! 


Expert Mode Options 


The "Cluster" installer includes an expert mode to enable extra options for those who needs them. If 
you are not that familiar with Linux or ViciDial then most likely you do not need any of the options 
offered by expert mode. Improperly setting things in expert mode can have a detrimental effect to the 
efficiency and operation of a cluster. 


Below are the extra prompts offered by the expert mode install: 
e Slave Database installation 
e Install index.php to redirect user to the ViciDial welcome screen (enabled by default) 
°- Install phpMyAdmin (disabled by default) 
e Supply connection settings for use by the Archive server role 


Legacy Mode 


Legacy mode enables support for legacy ViciDial installs not installed using ViciBox v.4.0+. Your 
installation must be using an SVN "Trunk" Revision in order to be compatible with ViciBox v.4.0. You 
will also need to know what SVN revision your other servers are using in order for ViciBox to 
complete it's install. A method to add the 'vicibox' table used by ViciBox v.4.0+ to older installations is 
currently planned but not available yet. 


The 'ngrep-sip' command 


There is an amazingly useful but little known utility that has been included in ViciBox v.3.1+ called 
‘ngrep-sip'. What this does is use ngrep, a network-grep'ing utility', and scans for SIP traffic. It's use is 
pretty straightforward, you type 'ngrep-sip' and it gives SIP output. In addition to this, you can scan for 
SIP traffic to a certain host or for a specific phone number. For instance, if you want to see the SIP 
messages going to phone number 8633939330, you would run 'ngrep-sip 8633939330". It will then only 
show you SIP messages that have that phone number in it. You can also use host to specify only a 
certain host. So if you wanted to see SIP messages going to a new carrier with IP A.B.C.D, you would 
type 'ngrep-sip host A.B.C.D'. You can also capture these messages to send to carriers when they 
inevitably tell you everything is great but they are broken. It should be noted that ngrep-sip does not 


display correctly when using VLANs on your network, but it is still close enough to be readable if you 
understand SIP messaging. There is a config file located at /etc/ngrep-sip.conf if you want to change 
the standard network interface it listens to when ran. Remember, with all carriers, you are wrong until 
YOU have proven otherwise. 


The 'mysql-tuning' command 


The 'mysql-tuning' script will look at your currently running MySQL configuration and give you 
generalized recommendations on tuning your my.cnf settings as well as show where any potential 
problems are. This is especially useful for when things seem to be slowing down but nothings looks 
obviously wrong. This is useful for when you hit your MySQL configured max connection limit. It will 
also show you if you have ever allocated more memory then you have RAM which means you 
swapped out to disk. All very useful things, but it is not 100% accurate in it's recommendations. It is 
merely a tool used to guide you in the diagnosis of a problem. It should not be used for fine tuning but 
for diagnostic and broad tuning. 


Zoiper Web Phone is installed 


The zoiper web phone is installed by default on all version of ViciBox and works for up to 3 minutes if 
you want to test it. The web phone is Windows only and best installed initially from Internet Explorer. 
Point IE to http://webserver.ip/agc/webphone/ and it should download and install. Once installation is 
complete, the webphone works from IE, FireFox, and Chrome. The Zoiper Web Phone License can be 
purchased from the ViciDial Group and installed for you or you can purchase it directly from Zoiper 
and install it. The web phone is based upon your fully qualified domain name (FQDN) and is non- 
refundable once issues. This means that if you tell them to generate the license for 
http://my.webserver.com and you then later decide you wanted it to be http://some.webserver.com the 
license will not work. You will have to purchase a second license for the new FQDN or stay with the 
old server name. You also need to use a domain name as it will not work with IP Addressing directly. 


Integrated ipset with built-in firewall 


IPSet has been integrated with the build in SuSEfirewall2 script to provide a simple mechanism to 
block malicious IP address’. This is a simple IP hash list of single IP address' that are set in an iptables 
rule to drop any packets sent to or received from them. You can view the IP's in the list by typing 'ipset 
-L badips' and pressing ENTER. To add an IP to this list you would type 'ipset add badips X.X.X.X' 
replacing the X.X.X.X with the offending IP. To remove an IP from this list you would type 'ipset del 
badips X.X.X.X' replacting the X.X.X.X with the IP to remove. There is currently no facility in place to 
save and manage the IP's that are put into this list so any data put in IPSet will be lost upon reboot. To 
have the IP's persist after reboot you can add the command to add the individual IPs to the end of the 
/etc/init.d/after.local file. This will make sure any IP you block will stay blocked. 


VoiceMail spool manager utility 


A utility has been added to vicibox located at /usr/local/bin/vmspool_manager.pl. It's primary purpose 
is to allow you to trim voicemail boxes of any messages older then X days. You would use it by logging 


into the server and typing 'vmspool_manager.pl --age=X --active' replacing X with the number of days 
that voicemail should be kept. For instance, replacing X with 14 will delete any voicemails that are 
older then 14 days. You can also use --mailbox=Y to only look through certain mailboxes as opposed to 
all mailboxes on the system. It is recommended to run this periodically if you are not emailing and 
deleting voicemails by default. 


Feedback and Community Support 


We like hearing from you. Whether it is bugs, condemnation, or praise, we like it. It helps us to 
improve both ViciDial and ViciBox. Without your feedback things will not improve or move in the 
direction the community wants it to. Please take some time to log into the community forums at 
http://www.vicidial.org/VICIDIALforum/ and let us know how you did, good or bad. You will find the 
array of talent available there to be excellent as well as the breadth of knowledge already posted. 


Please remember to search for any issues or topics prior to posting to see if your question has already 
been answered. In addition to getting you your answer quicker, it also makes others more likely to 
respond when they know you searched first. 


When posting on the forum, it is considered proper etiquette to state what installation medium you 
used, what the ViciDial Admin and Build date are from the administration interface, what SVN revision 
you are using, and any other pertinent information that might relate to your issue or bug. For instance, 
using the version of ViciDial shipped on ViciBox v.4.0.0, with a 75-agent outbound cluster using the 
dimensioning mentioned previously, you would want to include the following in your post so we know 
how best to start helping you: 


ViciBox v.4.0.0 32-bit preload 

Build: 120831-1528 

Version: 2.6-375a 

SVN Rev: 1858 

1xDB, 1x Web, 3xTelephony, 1x Archive 


Credits and Thanks 


Thanks go out to all the active members of the ViciDial Community Forums and those companies and 
individuals who sponsor features in ViciDial and ViciBox. These guys make things happen and push us 
to release bigger and better versions of ViciDial and ViciBox. They have committed code snippets for 
improving functionality, paid for features that everyone gets to use, and beta tested early versions to try 
and find bugs before general release. Stop by and say thanks, they like it. 


ViciDial was initially written and copyright by Matthew Florell. 

ViciBox was conceived and initially written by Michael Cargile from the ViciDial Group. 

ViciBox is currently written and maintained by James Pearson from the ViciDial Group. 

Iterative testing and verification performed by Keith Hughes, Robert Reeder, Michael Coate, and Matt 
Borchert from the ViciDial Group. 


